Crate axum_test

Axum Test is a library for writing tests for web servers written using Axum:

• You create a TestServer within a test,
• use that to build TestRequest against your application,
• receive back a TestResponse,
• then assert the response is how you expect.

It includes built in support for serializing and deserializing request and response bodies using Serde, support for cookies and headers, and other common bits you would expect.

TestServer will pass http requests directly to the handler, or can be run on a random IP / Port address.

Getting Started

Create a TestServer running your Axum Router:

use ::axum::Router;
use ::axum::extract::Json;
use ::axum::routing::put;
use ::axum_test::TestServer;
use ::serde_json::json;
use ::serde_json::Value;

async fn route_put_user(Json(user): Json<Value>) -> () {
    // todo
}

let my_app = Router::new()
    .route("/users", put(route_put_user));

let server = TestServer::new(my_app)?;

Then make requests against it:

let response = server.put("/users")
    .json(&json!({
        "username": "Terrance Pencilworth",
    }))
    .await;

Features

Auto Cookie Saving 🍪

This feature allows the server to save cookies and reuse these on future requests. For example saving session cookies, like a browser would.

This feature is disabled by default, and can be enabled by setting save_cookies to true on the TestServerConfig, and passing this to the TestServer on construction.

use ::axum::Router;
use ::axum_test::TestServer;
use ::axum_test::TestServerConfig;

let my_app = Router::new();
let config = TestServerConfig::builder()
    .save_cookies()
    .build();

let server = TestServer::new_with_config(my_app, config)?;

When you make a request, any cookies returned will be reused by the next request, created by that same server.

You can turn this on or off per request, using TestRequest::do_save_cookies and TestRequest::do_not_save_cookies.

Content Type 📇

When performing a request, it will start with no content type at all.

You can set a default type for all TestRequest objects to use, by setting the default_content_type in the TestServerConfig. When creating the TestServer instance, using new_with_config.

use ::axum::Router;
use ::axum_test::TestServer;
use ::axum_test::TestServerConfig;

let my_app = Router::new();
let config = TestServerConfig::builder()
    .default_content_type("application/json")
    .build();

let server = TestServer::new_with_config(my_app, config)?;

If there is no default, then a TestRequest will try to guess the content type. Such as setting application/json when calling TestRequest::json, and text/plain when calling TestRequest::text. This will never override any default content type provided.

Finally on each TestRequest, one can set the content type to use. By calling TestRequest::content_type on it.

use ::axum::Router;
use ::axum::extract::Json;
use ::axum::routing::put;
use ::axum_test::TestServer;
use ::serde_json::json;
use ::serde_json::Value;

async fn put_user(Json(user): Json<Value>) -> () {
    // todo
}

let my_app = Router::new()
    .route("/users", put(put_user));

let server = TestServer::new(my_app)?;

let response = server.put("/users")
    .content_type(&"application/json")
    .json(&json!({
        "username": "Terrance Pencilworth",
    }))
    .await;

Fail Fast ⚡️

This library includes a mode to have requests panic if they are outside of the 2xx range, unless marked by calling TestRequest::expect_failure(). This is intentional to aid with writing tests, and to help catch errors quickly when making code changes.

This behaviour is off by default, and can be enabled by setting TestServerConfig::expect_success_by_default to true when creating a new TestServer.

Re-exports

• pub use ::http;

Modules

• multipart
  This supplies the building blocks for sending multipart forms using TestRequest::multipart().
• transport_layer
• util

Structs

• TestRequest
  A TestRequest is for building and executing a HTTP request to the TestServer.
• TestResponse
  The TestResponse is the result of a request created using a TestServer. The TestServer builds a TestRequest, which when awaited, will produce the response.
• TestServer
  The TestServer runs your Axum application, allowing you to make HTTP requests against it.
• TestServerConfig
  This is for customising the TestServer on construction.
• TestServerConfigBuilder
  This is for easing the building of TestServerConfig.

Enums

• Transport
  Transport is for setting which transport mode for the TestServer to use when making requests.